Claude Code 安装、IDE 配置与常见报错处理

最近折腾了一下 Claude Code 的安装和 IDE 集成，这里顺手整理一份相对完整的安装说明，方便后面自己查，也方便有需要的朋友直接照着配置。

这篇主要包含三部分内容：安装方式、报错时的替代安装方案，以及 Cursor / VSCode / JetBrains 中的插件配置流程。

一、Claude Code 安装方式

1. 官方脚本安装

如果网络环境正常，优先推荐使用官方脚本安装，步骤会更简单一些。

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

说明：这几种官方方式通常需要科学上网环境。

2. 出现“不支持的地区”时的替代方案

如果在安装过程中提示“不支持的地区”之类的错误，可以改用下面两种方式。

NPM 安装

npm install -g @anthropic-ai/claude-code@2.1.110 --registry=https://registry.npmmirror.com

补充说明：

• 目前 claude-code 从 2.1.112+ 之后，npm 安装方式不再直接支持
• 如果你已经通过旧版本完成安装，后续可以手动执行下面的命令升级

claude install

Homebrew 安装

brew install --cask claude-code
brew upgrade claude-code

二、安装后的注意事项

下载并安装完成后，建议先不要急着直接打开 Claude Code，最好先把 IDE 插件配置好，再开始使用。这样后续在编辑器里联动会更顺一些，也能少踩一点初始化过程中的坑。

三、Cursor 安装方式（VSCode 同理）

Cursor 和 VSCode 的安装思路基本一致，这里以 Cursor 为例说明。

1. 打开扩展市场

在 Cursor 左侧边栏中打开“扩展”页面。

2. 搜索并安装插件

搜索：

Claude Code

然后选择：

Claude Code for VSCode

参考图片：

3. 安装异常时

如果在 Cursor 插件安装过程中遇到问题，可以结合你自己后续整理的常见问题一起排查，例如网络、代理、扩展市场加载失败等问题。

四、JetBrains IDE 安装方式

这里以 Goland 为例，其它 JetBrains 系列 IDE 的操作步骤基本类似。

1. 打开设置

在 Goland 主界面右上角进入设置页面。

参考图片：

2. 搜索插件

进入：

插件 -> Marketplace

搜索：

claude code

参考图片：

3. 安装并唤起

安装完成后，回到 IDE 主界面，点击右上角的 Claude 图标即可唤起。

参考图片：

五、常见报错处理

1. 提示“不支持的地区”

这种情况通常出现在使用官方安装脚本时，本质上还是网络环境或地区限制导致的。

处理方式：

• 优先确认当前网络环境是否可正常访问官方服务
• 如果官方脚本无法使用，直接改用 npm 或 Homebrew 安装
• npm 安装时可以优先使用你已经验证可行的镜像源

npm install -g @anthropic-ai/claude-code@2.1.110 --registry=https://registry.npmmirror.com

2. 安装后执行 claude 提示命令不存在

如果安装完成后终端提示：

command not found: claude

一般是下面几种原因：

• 安装没有成功完成
• 全局安装目录没有加入环境变量
• 终端还没有重新加载配置

可以按下面顺序排查：

1. 先重新打开一个终端窗口再试一次
2. 如果是 npm 全局安装，检查全局 bin 目录是否在 PATH 中
3. 如果是 brew 安装，确认 brew 的环境变量已经生效

3. Cursor / VSCode 中搜索不到 Claude Code 插件

这类问题一般和扩展市场访问异常有关，常见原因包括：

• 网络不稳定
• 代理未正确生效
• 扩展市场加载失败
• 编辑器版本过旧

建议处理方式：

1. 先确认扩展市场本身能否正常打开
2. 检查代理设置是否已经生效
3. 重启 Cursor 或 VSCode 后重新搜索
4. 必要时升级编辑器到较新的版本再尝试

4. JetBrains 插件安装后没有显示入口

如果插件已经安装，但右上角没有看到 Claude 图标，可以按下面方式排查：

1. 先重启 IDE
2. 确认插件是否真正处于启用状态
3. 检查当前 IDE 版本是否兼容该插件
4. 如果仍然没有入口，可以尝试卸载后重新安装

5. 使用 npm 安装后无法直接升级

目前你这套安装说明里提到的一个关键点是：

• claude-code 在 2.1.112+ 之后，npm 安装方式不再直接支持

所以如果你是通过旧版本装上的，后续升级可以优先尝试：

claude install

如果升级过程中继续报错，建议优先考虑切换到官方安装方式或 Homebrew 方式维护版本。

六、总结

整体来说，如果网络环境允许，还是优先推荐官方脚本安装；如果遇到地区限制，再考虑 npm 或 Homebrew 方式。

安装好本体之后，再把 Cursor / VSCode / JetBrains 中的插件补齐，基本就可以比较顺畅地开始用了。